CS-11655: add app.boxel.realm-servers event type + read/write helpers by lukemelia · Pull Request #5284 · cardstack/boxel

lukemelia · 2026-06-18T17:42:12Z

Summary

Foundational data-model change for the Rework Realms List Source-of-Truth project. Introduces the app.boxel.realm-servers account-data event type so a user's Matrix account data can carry the set of trusted realm servers alongside the existing flat realm list. Boot assembly (CS-11658) and lazy migration (CS-11659) land in follow-ups; this PR is plumbing-only.

runtime-common — new APP_BOXEL_REALM_SERVERS_EVENT_TYPE constant and AppBoxelRealmServersContent payload type.
host matrix-service — get/set/append/remove RealmServers...AccountData helpers mirroring the existing realms helpers. Legacy app.boxel.realms behavior is unchanged.
realm-server synapse — parallel appendRealmServerToUserAccountData with the same idempotent retry-on-stomp semantics. The existing fetch/put plumbing is factored to take an eventType so both helpers share it.
realm-server upsert-permission handler — after the existing realm append, also writes the realm-server origin to app.boxel.realm-servers so both keys stay in lockstep going forward.
mock matrix client — handles get/set + AccountData event routing for the new key, with a new activeRealmServers config option.

Acceptance criteria (from CS-11655)

New constant and payload type exported from runtime-common.
Helpers to read and write app.boxel.realm-servers account data exist and are typed.
Legacy app.boxel.realms behavior is unchanged.

Test plan

pnpm lint:types clean in runtime-common, host, realm-server.
pnpm lint:js clean in runtime-common, host, realm-server.
pnpm prettier --check on all touched files.
CI: host integration test Integration | matrix-service | realm-servers account data — round-trips the payload, append idempotency, remove leaves other entries.
CI: realm-server endpoint tests — appendRealmServerToUserAccountData preserves prior entries; grafana upsert populates app.boxel.realm-servers with the realm-server origin.

🤖 Generated with Claude Code

Foundational data-model change for the source-of-truth rework. A user's matrix account data should store the set of *trusted realm servers* alongside the existing flat realm list during the transition. Boot assembly and lazy migration land in follow-ups (CS-11658, CS-11659). - runtime-common: new APP_BOXEL_REALM_SERVERS_EVENT_TYPE constant and AppBoxelRealmServersContent payload type. - host matrix-service: get/set/append/remove helpers for the new key, mirroring the existing realms helpers. Legacy realms behavior is unchanged. - realm-server synapse: parallel appendRealmServerToUserAccountData with the same idempotent retry-on-stomp semantics (helpers factored to share the get/put plumbing). - realm-server upsert-permission handler: after the realm append, also writes the realm-server origin to app.boxel.realm-servers so both keys stay in lockstep during the transition. - mock matrix client: handles get/set + AccountData event routing for the new key, with a new activeRealmServers config option. - tests: host integration test round-trips the {realmServers} payload through the helpers (append idempotency, remove); realm-server endpoint tests cover direct helper behaviour and the grafana upsert sync path. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

github-actions · 2026-06-18T18:13:39Z

Preview deployments

Host staging preview

Host production preview

Realm Server Test Results

1 files 1 suites 12m 17s ⏱️
1 737 tests 1 737 ✅ 0 💤 0 ❌
1 830 runs 1 830 ✅ 0 💤 0 ❌

Results for commit fd64286.

lukemelia

[Codex] I reviewed PR 5284 and found one issue.

lukemelia · 2026-06-18T19:40:05Z

    );
-    let realms = Array.isArray(existing.realms) ? existing.realms : [];
-    if (realms.includes(realmURL)) {
+    let entries = Array.isArray(existing[arrayKey])


[Codex] This changes the legacy app.boxel.realms append behavior too: appendRealmToUserAccountData now routes through this helper, so any existing non-string entries in the realms array are filtered out and the PUT below writes back only entries. The previous implementation preserved the existing array contents exactly with realms: [...realms, realmURL]. Since this PR calls out legacy app.boxel.realms behavior as unchanged, please avoid sanitizing the stored array on write; if we want a string-only view for includes, keep that separate from the array we persist back.

low-risk, leaving as is

Copilot

Pull request overview

Adds plumbing for a new Matrix account-data event type (app.boxel.realm-servers) to store a user’s trusted realm-server origins, alongside helper APIs and test coverage across runtime-common, host, and realm-server.

Changes:

Introduces APP_BOXEL_REALM_SERVERS_EVENT_TYPE and AppBoxelRealmServersContent in runtime-common.
Adds host matrix-service read/write/append/remove helpers for the new account-data key, plus mock-matrix support and a new integration test.
Extends realm-server Synapse helpers and the Grafana upsert permission flow to keep app.boxel.realms and app.boxel.realm-servers in sync, with new endpoint tests.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/runtime-common/matrix-constants.ts	Adds new Matrix account-data event type constant and payload interface.
packages/realm-server/tests/server-endpoints/maintenance-endpoints-test.ts	Adds tests for realm-server account-data append behavior and Grafana upsert syncing.
packages/realm-server/synapse.ts	Refactors account-data append plumbing to support both realms and realm-servers.
packages/realm-server/handlers/handle-upsert-realm-user-permission.ts	Updates upsert flow to also append realm-server origin to new account-data key.
packages/matrix/support/matrix-constants.ts	Adds the new event type constant in matrix support utilities.
packages/host/tests/integration/matrix-service-realm-servers-test.ts	Adds integration tests for host matrix-service realm-servers account-data helpers.
packages/host/tests/helpers/mock-matrix/_client.ts	Extends mock Matrix client to get/set/route the new account-data event type.
packages/host/tests/helpers/mock-matrix.ts	Adds `activeRealmServers` option for mock-matrix configuration.
packages/host/app/services/matrix-service.ts	Adds host helpers to read/write/append/remove realm-server URLs in account data.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+  public async getRealmServersFromAccountData(): Promise<string[]> {
+    let { realmServers = [] } =
+      ((await this.client.getAccountDataFromServer(
+        APP_BOXEL_REALM_SERVERS_EVENT_TYPE,
+      )) as { realmServers: string[] }) ?? {};
+    return realmServers;
+  }


lukemelia commented Jun 18, 2026

View reviewed changes

lukemelia marked this pull request as ready for review June 18, 2026 19:45

lukemelia requested review from a team and jurgenwerk June 18, 2026 19:45

lukemelia mentioned this pull request Jun 18, 2026

CS-11658: boot assembly from trusted servers via _realm-auth #5285

Draft

5 tasks

habdelra requested a review from Copilot June 18, 2026 21:52

Copilot started reviewing on behalf of habdelra June 18, 2026 21:54 View session

Copilot AI reviewed Jun 18, 2026

View reviewed changes

FadhlanR approved these changes Jun 19, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CS-11655: add app.boxel.realm-servers event type + read/write helpers#5284

CS-11655: add app.boxel.realm-servers event type + read/write helpers#5284
lukemelia wants to merge 1 commit into
mainfrom
cs-11655-add-realm-servers-event-type

lukemelia commented Jun 18, 2026

Uh oh!

github-actions Bot commented Jun 18, 2026 •

edited

Loading

Uh oh!

lukemelia left a comment

Uh oh!

lukemelia Jun 18, 2026

Uh oh!

lukemelia Jun 18, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

lukemelia commented Jun 18, 2026

Summary

Acceptance criteria (from CS-11655)

Test plan

Uh oh!

github-actions Bot commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Preview deployments

Realm Server Test Results

Uh oh!

lukemelia left a comment

Choose a reason for hiding this comment

Uh oh!

lukemelia Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

lukemelia Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Jun 18, 2026 •

edited

Loading